home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1997 October: Mac OS SDK / Dev.CD Oct 97 SDK1.toast / Development Kits (Disc 1) / Interfaces&Libraries / Universal / Interfaces / CIncludes / QD3DExtension.h < prev    next >
Encoding:
C/C++ Source or Header  |  1997-08-12  |  10.5 KB  |  357 lines  |  [TEXT/MPS ]
  1. /******************************************************************************
  2.  **                                                                             **
  3.  **     Module:        QD3DExtension.h                                             **
  4.  **                                                                          **
  5.  **                                                                          **
  6.  **     Purpose:     QuickDraw 3D Plug-in Architecture                         **
  7.  **                                                                          **
  8.  **                                                                          **
  9.  **                                                                          **
  10.  **     Copyright (C) 1992-1997 Apple Computer, Inc.  All rights reserved.     **
  11.  **                                                                          **
  12.  **                                                                          **
  13.  *****************************************************************************/
  14. #ifndef QD3DExtension_h
  15. #define QD3DExtension_h
  16.  
  17. #include "QD3D.h"
  18. #include "QD3DErrors.h"
  19.  
  20. #if defined(PRAGMA_ONCE) && PRAGMA_ONCE
  21.     #pragma once
  22. #endif  /*  PRAGMA_ONCE  */
  23.  
  24. #if defined(OS_MACINTOSH) && OS_MACINTOSH
  25.  
  26. #if defined(__xlc__) || defined(__XLC121__)
  27.     #pragma options enum=small
  28. #endif
  29.  
  30. #include <CodeFragments.h>
  31.  
  32. #if defined(__xlc__) || defined(__XLC121__)
  33.     #pragma options enum=reset
  34.     #pragma options enum=int
  35.     #pragma options align=power
  36. #elif defined(__MWERKS__)
  37.     #pragma enumsalwaysint on
  38.     #pragma options align=native
  39. #elif defined(__MRC__) || defined(__SC__)
  40.     #if __option(pack_enums)
  41.         #define PRAGMA_ENUM_RESET_QD3DEXTEN 1
  42.     #endif
  43.     #pragma options(!pack_enums)
  44.     #pragma options align=power
  45. #endif
  46.  
  47. #endif /* OS_MACINTOSH */
  48.  
  49.  
  50. #ifdef __cplusplus
  51. extern "C" {
  52. #endif  /* __cplusplus  */
  53.  
  54. /******************************************************************************
  55.  **                                                                             **
  56.  **                                Constants                                      **
  57.  **                                                                             **
  58.  *****************************************************************************/
  59.  
  60. #if defined(OS_MACINTOSH) && OS_MACINTOSH
  61.  
  62. #define kQ3XExtensionMacCreatorType        Q3_OBJECT_TYPE('Q','3','X','T')
  63. #define kQ3XExtensionMacFileType        Q3_OBJECT_TYPE('s','h','l','b')
  64.  
  65. #endif  /*  OS_MACINTOSH  */
  66.  
  67.  
  68. /******************************************************************************
  69.  **                                                                             **
  70.  **                                    Macros                                      **
  71.  **                                                                             **
  72.  *****************************************************************************/
  73.  
  74. /*
  75.  * Use this Macro to pack the version number for your class.  This would most
  76.  * likely get used in the  kQ3XMethodTypeObjectClassVersion to return the 
  77.  * version for your class.  This method is set up in your meta handler.
  78.  */
  79.  
  80. #define Q3_OBJECT_CLASS_VERSION(major, minor)            \
  81.     (unsigned long) (((major) << 16) | (minor))
  82.  
  83. /*
  84.  * Convenience macros to unpack a version number, accessing the major and the
  85.  * minor version numbers
  86.  */
  87. #define Q3_OBJECT_CLASS_GET_MAJOR_VERSION(version)        \
  88.     (unsigned long) ((version) >> 16)
  89.  
  90. #define Q3_OBJECT_CLASS_GET_MINOR_VERSION(version)        \
  91.     (unsigned long) ((version) & 0x0000FFFF)
  92.  
  93.  
  94.  
  95. /******************************************************************************
  96.  **                                                                             **
  97.  **                                Object Method types                              **
  98.  **                                                                             **
  99.  *****************************************************************************/
  100.  
  101. #define kQ3XMethodTypeObjectClassVersion        Q3_METHOD_TYPE('v','r','s','n')
  102. typedef unsigned long    TQ3XObjectClassVersion;
  103.  
  104. #define kQ3XMethodTypeObjectClassRegister        Q3_METHOD_TYPE('r','g','s','t')
  105. typedef TQ3Status (QD3D_CALLBACK *TQ3XObjectClassRegisterMethod)(
  106.     TQ3XObjectClass        objectClass,
  107.     void                *classPrivate);
  108.  
  109. #define kQ3XMethodTypeObjectClassReplace        Q3_METHOD_TYPE('r','g','r','p')
  110. typedef void (QD3D_CALLBACK *TQ3XObjectClassReplaceMethod)(
  111.     TQ3XObjectClass        oldObjectClass,
  112.     void                *oldClassPrivate,
  113.     TQ3XObjectClass        newObjectClass,
  114.     void                *newClassPrivate);
  115.  
  116. #define kQ3XMethodTypeObjectClassUnregister        Q3_METHOD_TYPE('u','n','r','g')
  117. typedef void (QD3D_CALLBACK *TQ3XObjectClassUnregisterMethod)(
  118.     TQ3XObjectClass        objectClass,
  119.     void                *classPrivate);
  120.     
  121. #define kQ3XMethodTypeObjectNew                    Q3_METHOD_TYPE('n','e','w','o')
  122. typedef TQ3Status (QD3D_CALLBACK *TQ3XObjectNewMethod)(
  123.     TQ3Object            object,
  124.     void                *privateData,        
  125.     void                *parameters);        
  126.  
  127. #define kQ3XMethodTypeObjectDelete                Q3_METHOD_TYPE('d','l','t','e')
  128. typedef void (QD3D_CALLBACK *TQ3XObjectDeleteMethod)(
  129.     TQ3Object            object,
  130.     void                *privateData);
  131.     
  132.  
  133. #define kQ3XMethodTypeObjectDuplicate            Q3_METHOD_TYPE('d','u','p','l')
  134. typedef TQ3Status (QD3D_CALLBACK *TQ3XObjectDuplicateMethod)(
  135.     TQ3Object            fromObject,
  136.     const void            *fromPrivateData,
  137.     TQ3Object            toObject,
  138.     const void            *toPrivateData);
  139.  
  140. typedef TQ3Status (QD3D_CALLBACK *TQ3XSharedLibraryRegister)(
  141.     void);
  142.  
  143.  
  144. /******************************************************************************
  145.  **                                                                             **
  146.  **                            Object Hierarchy Registration                      **
  147.  **                                                                             **
  148.  *****************************************************************************/
  149.  
  150. /*
  151.  *    Q3XObjectHierarchy_RegisterClass
  152.  *    
  153.  *    Register an object class in the QuickDraw 3D hierarchy.
  154.  *    
  155.  *    parentType            - an existing type in the hierarchy, or 0 to subclass
  156.  *                            TQ3Object
  157.  *    objectType            - the new object class type, used in the binary 
  158.  *                        metafile.  This is assigned at run time and returned
  159.  *                          to you.
  160.  *    objectName            - the new object name, used in the text metafile
  161.  *    metaHandler            - a TQ3XMetaHandler (may be NULL for some classes) 
  162.  *                          which returns non-virtual methods
  163.  *    virtualMetaHandler    - a TQ3XMetaHandler (may be NULL as well) which returns
  164.  *                            virtual methods a child would inherit
  165.  *    methodsSize            - the size of the class data needed (see 
  166.  *                            GetClassPrivate calls below)
  167.  *    instanceSize        - the size of the object instance data needed (see 
  168.  *                            GetPrivate calls below)
  169.  */
  170. QD3D_EXPORT TQ3XObjectClass QD3D_CALL Q3XObjectHierarchy_RegisterClass(
  171.     TQ3ObjectType            parentType,
  172.     TQ3ObjectType            *objectType,
  173.     char                    *objectName,
  174.     TQ3XMetaHandler            metaHandler,
  175.     TQ3XMetaHandler            virtualMetaHandler,
  176.     unsigned long            methodsSize,
  177.     unsigned long            instanceSize);
  178.  
  179. /*
  180.  *    Q3XObjectHierarchy_UnregisterClass
  181.  *    
  182.  *    Returns kQ3Failure if the objectClass still has objects 
  183.  * around; the class remains registered.
  184.  */
  185. QD3D_EXPORT TQ3Status QD3D_CALL Q3XObjectHierarchy_UnregisterClass(
  186.     TQ3XObjectClass            objectClass);
  187.  
  188. /*
  189.  *    Q3XObjectClass_GetMethod
  190.  *    
  191.  *    For use in TQ3XObjectClassRegisterMethod call
  192.  */
  193. QD3D_EXPORT TQ3XFunctionPointer QD3D_CALL Q3XObjectClass_GetMethod(
  194.     TQ3XObjectClass            objectClass,
  195.     TQ3XMethodType            methodType);
  196.  
  197. /*
  198.  *    Q3XObjectHierarchy_NewObject
  199.  *    
  200.  *    To create a new object. Parameters is passed into the 
  201.  *    TQ3XObjectNewMethod as the "parameters" parameter.
  202.  */
  203. QD3D_EXPORT TQ3Object QD3D_CALL Q3XObjectHierarchy_NewObject(
  204.     TQ3XObjectClass            objectClass,
  205.     void                    *parameters);
  206.  
  207. /*
  208.  *    Q3XObjectClass_GetLeafType
  209.  *    
  210.  *    Return the leaf type of a class.
  211.  */
  212. QD3D_EXPORT TQ3ObjectType QD3D_CALL Q3XObjectClass_GetLeafType(
  213.     TQ3XObjectClass            objectClass);
  214.  
  215. /*
  216.  *    Q3XObjectHierarchy_GetClassVersion
  217.  *
  218.  *    This routine obtains the the version of a class, referenced by an
  219.  *    object class type.  Functions for getting the type are in QD3D.h,
  220.  *    if you have the class name.
  221.  */ 
  222. QD3D_EXPORT TQ3Status QD3D_CALL Q3XObjectHierarchy_GetClassVersion(
  223.     TQ3ObjectType            objectClassType,
  224.     TQ3XObjectClassVersion    *version);
  225.  
  226. /*
  227.  *    Q3XObjectClass_GetType 
  228.  *
  229.  *    This can be used to get the type, given a reference 
  230.  *    to a class.  This is most useful in the instance where you register a 
  231.  *    an element/attribute and need to get the type.  When you register an
  232.  *    element, QD3D will take the type you pass in and modify it (to avoid
  233.  *    namespace clashes).  Many object system calls require an object type
  234.  *    so this API call allows you to get the type from the class referernce
  235.  *    that you will ordinarily store when you register the class.
  236.  */
  237. QD3D_EXPORT TQ3Status QD3D_CALL Q3XObjectClass_GetType( 
  238.     TQ3XObjectClass         objectClass, 
  239.     TQ3ObjectType             *type);
  240.  
  241.  
  242. QD3D_EXPORT TQ3XObjectClass QD3D_CALL Q3XObjectHierarchy_FindClassByType(
  243.     TQ3ObjectType            type);
  244.  
  245.  
  246.  
  247. /*
  248.  *    Q3XObjectClass_GetPrivate
  249.  *    
  250.  *    Return a pointer to private instance data, a block of instanceSize bytes, 
  251.  *    from the Q3XObjectHierarchy_RegisterClass call.
  252.  *    
  253.  *    If instanceSize was zero, NULL is always returned.
  254.  */
  255. QD3D_EXPORT void *QD3D_CALL Q3XObjectClass_GetPrivate(
  256.     TQ3XObjectClass            objectClass,
  257.     TQ3Object                targetObject);
  258.         
  259. /*
  260.  * Return the "TQ3XObjectClass" of an object
  261.  */
  262. QD3D_EXPORT TQ3XObjectClass QD3D_CALL Q3XObject_GetClass(
  263.     TQ3Object         object);
  264.     
  265.  
  266.  
  267. /******************************************************************************
  268.  **                                                                             **
  269.  **                    Shared Library Registration Entry Point                      **
  270.  **                                                                             **
  271.  *****************************************************************************/
  272.  
  273. typedef struct TQ3XSharedLibraryInfo {
  274.     TQ3XSharedLibraryRegister    registerFunction;    
  275.     unsigned long                sharedLibrary;
  276. } TQ3XSharedLibraryInfo;
  277.  
  278. QD3D_EXPORT TQ3Status QD3D_CALL Q3XSharedLibrary_Register(
  279.     TQ3XSharedLibraryInfo    *sharedLibraryInfo);
  280.  
  281. QD3D_EXPORT TQ3Status QD3D_CALL Q3XSharedLibrary_Unregister(
  282.     unsigned long            sharedLibrary);
  283.     
  284.  
  285. /******************************************************************************
  286.  **                                                                             **
  287.  **                                Posting Errors                                  **
  288.  **                                                                             **
  289.  **            You may only call these functions from within an extension         **
  290.  **                                                                             **
  291.  *****************************************************************************/
  292.  
  293. /*
  294.  *    Q3XError_Post
  295.  *    
  296.  *    Post a QuickDraw 3D Error from an extension.
  297.  */
  298. QD3D_EXPORT void QD3D_CALL Q3XError_Post(
  299.     TQ3Error        error);
  300.  
  301. /*
  302.  *    Q3XWarning_Post
  303.  *    
  304.  *    Post a QuickDraw 3D Warning, from an extension.  Note the warning code you
  305.  *    pass into this routine must already be defined in the table above.
  306.  */
  307. QD3D_EXPORT void QD3D_CALL Q3XWarning_Post(
  308.     TQ3Warning        warning);
  309.  
  310. /*
  311.  *    Q3XNotice_Post
  312.  *    
  313.  *    Post a QuickDraw 3D Notice, from an extension.  Note the notice code you
  314.  *    pass into this routine must already be defined in the table above.
  315.  */
  316. QD3D_EXPORT void QD3D_CALL Q3XNotice_Post(
  317.     TQ3Notice        notice);
  318.  
  319.  
  320. #if defined(OS_MACINTOSH) && OS_MACINTOSH
  321.  
  322. /*
  323.  *    Q3XMacintoshError_Post
  324.  *    
  325.  *    Post the QuickDraw 3D Error, kQ3ErrorMacintoshError, and the Macintosh
  326.  *    OSErr macOSErr. (Retrieved with Q3MacintoshError_Get)
  327.  */
  328. QD3D_EXPORT void QD3D_CALL Q3XMacintoshError_Post(
  329.     OSErr            macOSErr);
  330.  
  331. #endif  /*  OS_MACINTOSH  */
  332.  
  333.  
  334. #ifdef __cplusplus
  335. }
  336. #endif  /* __cplusplus  */
  337.  
  338. #if defined(OS_MACINTOSH) && OS_MACINTOSH
  339.  
  340. #if defined(__xlc__) || defined(__XLC121__)
  341.     #pragma options enum=reset
  342.     #pragma options align=reset
  343. #elif defined(__MWERKS__)
  344.     #pragma enumsalwaysint reset
  345.     #pragma options align=reset
  346. #elif defined(__MRC__) || defined(__SC__)
  347.     #if PRAGMA_ENUM_RESET_QD3DEXTEN
  348.         #pragma options(pack_enums)
  349.         #undef PRAGMA_ENUM_RESET_QD3DEXTEN
  350.     #endif
  351.     #pragma options align=reset
  352. #endif
  353.  
  354. #endif  /* OS_MACINTOSH */
  355.  
  356. #endif  /* QD3DExtension_h  */
  357.